@octokit/request

What is @octokit/request?

The @octokit/request npm package is a low-level client for making authenticated requests to GitHub's REST API. It simplifies the process of making HTTP requests to GitHub's API endpoints, handling authentication, and parsing responses. It's part of the Octokit family of tools designed to work with GitHub in various programming languages and environments.

What are @octokit/request's main functionalities?

Making authenticated requests

This feature allows you to make authenticated requests to GitHub's REST API. You can retrieve or manipulate data related to repositories, issues, pull requests, and more. The code sample demonstrates how to fetch issues from a specific repository using a personal access token for authentication.

{
  "const { request } = require('@octokit/request');
  request('GET /repos/{owner}/{repo}/issues', {
    owner: 'octocat',
    repo: 'hello-world',
    headers: {
      authorization: 'token <YOUR_PERSONAL_ACCESS_TOKEN>'
    }
  });"
}

Custom requests

Beyond fetching data, @octokit/request can also be used to create or update resources on GitHub, such as issues, pull requests, and more. The code sample shows how to create a new issue in a repository, demonstrating the package's capability for making various types of authenticated requests.

{
  "const { request } = require('@octokit/request');
  request('POST /repos/{owner}/{repo}/issues', {
    owner: 'octocat',
    repo: 'hello-world',
    title: 'New issue title',
    body: 'Description of the new issue',
    headers: {
      authorization: 'token <YOUR_PERSONAL_ACCESS_TOKEN>'
    }
  });"
}

Other packages similar to @octokit/request

axios

Axios is a promise-based HTTP client for the browser and node.js. It supports request and response interception, client-side protection against XSRF, and more. While it is not specifically designed for GitHub's API, it can be used for similar purposes as @octokit/request by manually handling GitHub API endpoints and authentication.

node-fetch

node-fetch is a light-weight module that brings the Fetch API to Node.js. Like axios, it's a general-purpose HTTP client that can be used to interact with any REST API, including GitHub's. Compared to @octokit/request, node-fetch requires more manual setup for dealing with GitHub's API, such as handling authentication and parsing responses.

README

request.js

Send parameterized requests to GitHub’s APIs with sensible defaults in browsers and Node

@octokit/request is a request library for browsers & node that makes it easier to interact with GitHub’s REST API and GitHub’s GraphQL API.

It uses @octokit/endpoint to parse the passed options and sends the request using fetch (node-fetch when the runtime has no native fetch API).

• Features
• Usage
  • REST API example
  • GraphQL example
  • Alternative: pass method & url as part of options
• Authentication
• request()
• request.defaults()
• request.endpoint
• Special cases
  • The data parameter – set request body directly
  • Set parameters for both the URL/query and the request body
• LICENSE

Features

🤩 1:1 mapping of REST API endpoint documentation, e.g. Add labels to an issue becomes

request("POST /repos/{owner}/{repo}/issues/{number}/labels", {
  mediaType: {
    previews: ["symmetra"],
  },
  owner: "octokit",
  repo: "request.js",
  number: 1,
  labels: ["🐛 bug"],
});

👶 Small bundle size (<4kb minified + gzipped)

😎 Authenticate with any of GitHubs Authentication Strategies.

👍 Sensible defaults

• baseUrl: https://api.github.com
• headers.accept: application/vnd.github.v3+json
• headers.agent: octokit-request.js/<current version> <OS information>, e.g. octokit-request.js/1.2.3 Node.js/10.15.0 (macOS Mojave; x64)

👌 Simple to test: mock requests by passing a custom fetch method.

🧐 Simple to debug: Sets error.request to request options causing the error (with redacted credentials).

Usage

Browsers	Load @octokit/request directly from esm.sh <script type="module"> import { request } from "https://esm.sh/@octokit/request"; </script>
Node	Install with npm install @octokit/request const { request } = require("@octokit/request"); // or: import { request } from "@octokit/request";

REST API example

// Following GitHub docs formatting:
// https://developer.github.com/v3/repos/#list-organization-repositories
const result = await request("GET /orgs/{org}/repos", {
  headers: {
    authorization: "token 0000000000000000000000000000000000000001",
  },
  org: "octokit",
  type: "private",
});

console.log(`${result.data.length} repos found.`);

GraphQL example

For GraphQL request we recommend using @octokit/graphql

const result = await request("POST /graphql", {
  headers: {
    authorization: "token 0000000000000000000000000000000000000001",
  },
  query: `query ($login: String!) {
    organization(login: $login) {
      repositories(privacy: PRIVATE) {
        totalCount
      }
    }
  }`,
  variables: {
    login: "octokit",
  },
});

Alternative: pass method & url as part of options

Alternatively, pass in a method and a url

const result = await request({
  method: "GET",
  url: "/orgs/{org}/repos",
  headers: {
    authorization: "token 0000000000000000000000000000000000000001",
  },
  org: "octokit",
  type: "private",
});

Authentication

The simplest way to authenticate a request is to set the Authorization header directly, e.g. to a personal access token.

const requestWithAuth = request.defaults({
  headers: {
    authorization: "token 0000000000000000000000000000000000000001",
  },
});
const result = await requestWithAuth("GET /user");

For more complex authentication strategies such as GitHub Apps or Basic, we recommend the according authentication library exported by @octokit/auth.

const { createAppAuth } = require("@octokit/auth-app");
const auth = createAppAuth({
  appId: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY,
  installationId: 123,
});
const requestWithAuth = request.defaults({
  request: {
    hook: auth.hook,
  },
  mediaType: {
    previews: ["machine-man"],
  },
});

const { data: app } = await requestWithAuth("GET /app");
const { data: app } = await requestWithAuth(
  "POST /repos/{owner}/{repo}/issues",
  {
    owner: "octocat",
    repo: "hello-world",
    title: "Hello from the engine room",
  }
);

request()

request(route, options) or request(options).

Options

name	type	description
route	String	**Required**. If route is set it has to be a string consisting of the request method and URL, e.g. GET /orgs/{org}
options.baseUrl	String	The base URL that route or url will be prefixed with, if they use relative paths. Defaults to https://api.github.com.
options.headers	Object	Custom headers. Passed headers are merged with defaults: headers['user-agent'] defaults to octokit-rest.js/1.2.3 (where 1.2.3 is the released version). headers['accept'] defaults to application/vnd.github.v3+json. Use options.mediaType.{format,previews} to request API previews and custom media types.
options.mediaType.format	String	Media type param, such as `raw`, `html`, or `full`. See Media Types.
options.mediaType.previews	Array of strings	Name of previews, such as `mercy`, `symmetra`, or `scarlet-witch`. See API Previews.
options.method	String	Any supported http verb, case insensitive. Defaults to Get.
options.url	String	**Required**. A path or full URL which may contain :variable or {variable} placeholders, e.g. /orgs/{org}/repos. The url is parsed using url-template.
options.data	Any	Set request body directly instead of setting it to JSON based on additional parameters. See "The `data` parameter" below.
options.request.agent	http(s).Agent instance	Node only. Useful for custom proxy, certificate, or dns lookup.
options.request.fetch	Function	Custom replacement for built-in fetch method. Useful for testing or request hooks.
options.request.hook	Function	Function with the signature hook(request, endpointOptions), where endpointOptions are the parsed options as returned by endpoint.merge(), and request is request(). This option works great in conjuction with before-after-hook.
options.request.signal	new AbortController().signal	Use an AbortController instance to cancel a request. In node you can only cancel streamed requests.
options.request.log	object	Used for internal logging. Defaults to console.
options.request.timeout	Number	Node only. Request/response timeout in ms, it resets on redirect. 0 to disable (OS limit applies). options.request.signal is recommended instead.

All other options except options.request.* will be passed depending on the method and url options.

1. If the option key is a placeholder in the url, it will be used as replacement. For example, if the passed options are {url: '/orgs/{org}/repos', org: 'foo'} the returned options.url is https://api.github.com/orgs/foo/repos
2. If the method is GET or HEAD, the option is passed as query parameter
3. Otherwise the parameter is passed in the request body as JSON key.

Result

request returns a promise. If the request was successful, the promise resolves with an object containing 4 keys:

key	type	description
status	Integer	Response status status
url	String	URL of response. If a request results in redirects, this is the final URL. You can send a HEAD request to retrieve it without loading the full response body.
headers	Object	All response headers
data	Any	The response body as returned from server. If the response is JSON then it will be parsed into an object

If an error occurs, the promise is rejected with an error object containing 3 keys to help with debugging:

• error.status The http response status code
• error.request The request options such as method, url and data
• error.response The http response object with url, headers, and data

If the error is due to an AbortSignal being used, the resulting AbortError is bubbled up to the caller.

request.defaults()

Override or set default options. Example:

const myrequest = require("@octokit/request").defaults({
  baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
  headers: {
    "user-agent": "myApp/1.2.3",
    authorization: `token 0000000000000000000000000000000000000001`,
  },
  org: "my-project",
  per_page: 100,
});

myrequest(`GET /orgs/{org}/repos`);

You can call .defaults() again on the returned method, the defaults will cascade.

const myProjectRequest = request.defaults({
  baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
  headers: {
    "user-agent": "myApp/1.2.3",
  },
  org: "my-project",
});
const myProjectRequestWithAuth = myProjectRequest.defaults({
  headers: {
    authorization: `token 0000000000000000000000000000000000000001`,
  },
});

myProjectRequest now defaults the baseUrl, headers['user-agent'], org and headers['authorization'] on top of headers['accept'] that is set by the global default.

request.endpoint

See https://github.com/octokit/endpoint.js. Example

const options = request.endpoint("GET /orgs/{org}/repos", {
  org: "my-project",
  type: "private",
});

// {
//   method: 'GET',
//   url: 'https://api.github.com/orgs/my-project/repos?type=private',
//   headers: {
//     accept: 'application/vnd.github.v3+json',
//     authorization: 'token 0000000000000000000000000000000000000001',
//     'user-agent': 'octokit/endpoint.js v1.2.3'
//   }
// }

All of the @octokit/endpoint API can be used:

• octokitRequest.endpoint()
• octokitRequest.endpoint.defaults()
• octokitRequest.endpoint.merge()
• octokitRequest.endpoint.parse()

Special cases

The data parameter – set request body directly

Some endpoints such as Render a Markdown document in raw mode don’t have parameters that are sent as request body keys, instead the request body needs to be set directly. In these cases, set the data parameter.

const response = await request("POST /markdown/raw", {
  data: "Hello world github/linguist#1 **cool**, and #1!",
  headers: {
    accept: "text/html;charset=utf-8",
    "content-type": "text/plain",
  },
});

// Request is sent as
//
//     {
//       method: 'post',
//       url: 'https://api.github.com/markdown/raw',
//       headers: {
//         accept: 'text/html;charset=utf-8',
//         'content-type': 'text/plain',
//         'user-agent': userAgent
//       },
//       body: 'Hello world github/linguist#1 **cool**, and #1!'
//     }
//
// not as
//
//     {
//       ...
//       body: '{"data": "Hello world github/linguist#1 **cool**, and #1!"}'
//     }

Set parameters for both the URL/query and the request body

There are API endpoints that accept both query parameters as well as a body. In that case you need to add the query parameters as templates to options.url, as defined in the RFC 6570 URI Template specification.

Example

request(
  "POST https://uploads.github.com/repos/octocat/Hello-World/releases/1/assets{?name,label}",
  {
    name: "example.zip",
    label: "short description",
    headers: {
      "content-type": "text/plain",
      "content-length": 14,
      authorization: `token 0000000000000000000000000000000000000001`,
    },
    data: "Hello, world!",
  }
);

LICENSE

MIT